\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Basic User Interface Functions}

\beginChapter 2.{Common Lisp Object System Specification}%
{Basic User Interface Functions}{Basic User Interface Functions}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}
This chapter describes the functions provided by
the \CLOS\ Basic User Interface.
\vfill
\endSection%{Introduction}


\begincom{add-method}

\label Purpose:

The function {\bf add-method} adds a method to a generic function.  It returns
the modified generic function as its result.

\label Syntax:

\Defun {add-method} {generic-function options specialized-lambda-list function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it options\/} argument specifies the method combination options.

The {\it specialized-lambda-list\/} argument is a lambda list of the type that
may be given to {\bf defmethod}.

The {\it function\/} argument is the method function.

\label Values:

The modified generic function is returned as the result of {\bf add-method}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom


\begincom{argument-precedence-order}

\label Purpose:

The function {\bf argument-precedence-order} returns two values: a
list of the parameters of the generic function, in the order in which
they were specified, and a list of these same parameters, in order of
decreasing precedence.

\label Syntax:

\Defun {argument-precedence-order} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

\label Values:

Two values are returned: a list of the parameters of the generic
function and a list of the same parameters, in order of decreasing
precedence.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{call-next-method}

\label Purpose:

\label Syntax:

\label Examples:

\endcom



\begincom{change-class}

\label Purpose:

The function {\bf change-class} changes the class of an instance to the
new class.  It destructively modifies and returns the instance.

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument must be an instance whose metaclass is
{\bf class}.  % (a standard object)

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[The internal protocol of {\bf change-class} needs to be spec'd.]

\endcom



\begincom{class-of}

\label Purpose:

The function {\bf class-of} returns the class of a given object.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:


\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with {\bf make-instance}, the class that is
returned is the class that was specified as the {\it class\/} argument 
of {\bf make-instance}.

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
standard-type-class} or a subclass of {\bf standard-type-class} (other
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

Note that {\bf class-of} can never return an abstract class.

\endcom



\begincom{defclass}

\label Purpose:

The macro {\bf defclass} defines a new class.  It returns
the name of the new class as its result.

\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it name includes} \paren{\star{\curly{slot-description}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it includes\/}::$=$ (\star{\curly{class-name}})\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-description\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \brac{initform \star{\curly{slot-option}}})\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :initialize-only} {\it flag\/} $\vert$\cr
\+&&{\tt :accessor} {\it symbol\/} $\vert$ {\tt :accessor nil} $\vert$ \cr
\+&&{\tt :read-accessor} {\it symbol\/} $\vert$ {\tt :read-accessor nil} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type} \cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessors-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :readers-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&{\tt :constructor} $\vert$ ({\tt :constructor} {\it symbol\/}) $\vert$ ({\tt :constructor nil}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol boa-arglist\/}) $\vert$\cr
\+&&{\tt :predicate} $\vert$ ({\tt :predicate} {\it symbol\/}) $\vert$ ({\tt :predicate nil}) $\vert$\cr
\+&&({\tt :metaclass} {\it symbol\/}) \cr
\+&&({\tt :instantiable t}) $\vert$ ({\tt :instantiable nil}) \cr
\+&&({\tt :documentation} {\it string\/})\cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform} {\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject

\label Arguments:

[Discussion of {\bf defclass} syntax to go here.]

The {\bf :instantiable} option specifies whether it is possible to directly
instantiate this class with {\bf make-instance}.  If {\bf :instantiable} is
{\bf nil}, the class cannot be instantiated and is termed an {\bf abstract
class}.  The default value of {\bf :instantiable} is {\bf t}.

\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

All the classes in the included classes tree of a class must be defined
before an instance of the class may be created.

A class must be defined before it can be mentioned as an argument specializer
in a {\bf defmethod} form.

All the classes in the included classes tree of a class must be
defined before a {\bf with-slots} construct that makes reference to
that class may be evaluated (compiled).

\endcom



\begincom{defgeneric}

\label Purpose:

The macro {\bf defgeneric} defines a named generic function and stores it
in the symbol function cell of {\it name}.

\label Syntax:

\Defmac {defgeneric} {name lambda-list \ttbrac{documentation} \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-order-list\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{$\ldots$}}}

\label Arguments:

The {\it lambda-list\/} argument is a standard function lambda list.

The {\bf :method-combination-type} argument specifies the method combination
type for the generic function.    Its value can be either a method
combination type or the name of a method combination type.
%The default method combination type is {\bf :super-daemon}.

The {\bf :argument-precedence-order} argument is used to specify the
order in which the arguments in a call to the generic function are
tested for specificity when dispatching to a particular method.  The
{\bf :argument-precedence-order} argument is a list whose elements are
the symbols specified in the {\bf lambda-list\/}.  If no {\bf
:argument-precedence-order} argument is specified, the arguments in
the call to the generic function are tested for specificity in
left-to-right order.

A documentation string can be attached to the name of the generic
function by use of the optional {\it documentation\/} argument; the
documentation type for this string is {\bf function}.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function and use of {\bf defgeneric} is closely related to the
design of the method combination mechanism and the specification of
discrimination on optional arguments.
The name of {\bf defgeneric} is subject to change, depending on the
results of these decisions.

If a {\bf defgeneric} form is reevaluated, a new generic function is
installed in the symbol-function cell.

\endcom




\begincom{define-method-combination}

\label Purpose:

\label Syntax:

\label Arguments:

\label Values:

\label Examples:

\label Remarks:

\endcom



\begincom{defmethod}

\label Purpose:

The macro {\bf defmethod} defines a new method.  It returns the new method
as its result.

The argument list must be compatible with the argument list of the
generic function.
If this condition does not hold, an error is signalled.

[The following is under discussion:  A generic function of the given name
must exist before any methods of that name can be defined.]

\label Syntax:

\Defmac {defmethod} {name 
\star{\curly{option}}
\vtop{\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it option\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it thing}\cr
\Vskip 1pc!

\label Arguments:

[Discussion of {\bf defmethod} syntax to be written.]

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{defmethod-setf}

\label Purpose:

The macro {\bf defmethod-setf} defines a setf method.  [To be written.]

\label Syntax:

\Defmac {defmethod-setf} {name
\star{\curly{option}}
\vtop{\hbox{specialized-lambda-list setf-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it option\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it setf-lambda-list}::$=$ (\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it thing}\cr
\Vskip 1pc!

\label Arguments:

[Discussion of syntax to be written.]

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}

\label Purpose:

\label Syntax:

\Defun {describe} {object}

\label Arguments:

\label Values:

\label Examples:

\endcom



\begincom{documentation}


\label Purpose:

The Common Lisp function {\bf documentation} is extended as follows:
If the symbol names a generic function, {\bf documentation} returns the
documentation string for the generic function.  If the first argument is
a generic function, the documentation string of the generic is returned.
If the first argument is a method, the documentation string of the method
is returned.

\label Syntax:

\Defun documentation {symbol doc-type}

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function, or method. 

\endcom



\begincom{function-parameters}

\label Purpose:

The function {\bf function-parameters} returns the lambda list of its
argument from which default values for {\bf \&optional} and {\bf \&key}
parameters and supplied-p parameters have been removed.

[It is intended that this function correspond to whatever
{\bf function-parameters} is adopted for Common Lisp.]

\label Syntax:

\Defun {function-parameters} {function-or-generic-function}

\label Arguments:

The argument to {\bf function-parameters} is a function, generic function, or
a symbol that names a function or generic function.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The macro {\bf setf} can be used with {\bf function-parameters}.


\endcom

\begincom{generic-function-p}

\label Purpose:

The predicate {\bf generic-function-p} is true if its argument is a
generic function, otherwise it is false.

\label Syntax:

\Defun {generic-function-p} {object}

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{get-method}

\label Purpose:

The function {\bf get-method} takes a generic function and returns the
method object that has the given argument specializers and options.
If no such method exists, {\bf get-method} returns {\bf nil}.

\label Syntax:

\Defun {get-method} {generic-function options specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.  An error is signalled if no
such function exists.

The {\it options\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument specializers
for the method.  If {\it specializers\/} is {\bf nil}, the
default method function for that method is returned.

\endcom



\begincom{lambda-list-specializers}

\label Purpose:

The function {\bf lambda-list-specializers} takes a {\bf
defmethod} lambda list and returns a list containing the argument
specializers for all required arguments.  The specializer {\bf t} is
returned for any lambda list argument for which no argument specializer
was given.

\label Syntax:

\Defun {lambda-list-specializers} {specialized-lambda-list}

\endcom


\begincom{make-generic-function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

The function {\bf make-generic-function} is intended to be the
programmatic interface to {\bf defgeneric}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :function-parameters :argument-precedence-order}
\hbox{ :method-combination-type :documentation \dots}}}

\label Arguments:

The {\bf :function-parameters} argument is a lambda list.

The {\bf :argument-precedence-order} argument is a list that is a
permutation of the elements of the lambda list.

The {\bf :method-combination-type} argument is a symbol.

The {\bf :documentation} argument is a string.

\label See Also:

{\bf defgeneric}

\endcom

\begincom{make-instance}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class or a symbol that names a class.

\label Values:

\label Remarks:

[Discussion of initialization to go here.]

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

It is not possible to make an instance of class created with {\bf defclass}
if the {\bf :instantiable} option was {\bf nil}.  An error is signalled in
this case.

\label Examples:

\screen!

[To be written.]
\endscreen!


\label See Also:

{\bf class-of}

\endcom



\begincom{method-combination}

\label Purpose:

The function {\bf method-combination} returns the method combination
for the given generic function.

\label Syntax:

\Defun {method-combination} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic
function or a symbol that names a generic function.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{remove-class}

\label Purpose:

\label Syntax:

\Defun {remove-class} {class}

\label Arguments:

\label Values:

\label Examples:

\endcom



\begincom{remove-method}

\label Purpose:

The function {\bf remove-method} removes the method for the given
name, options, and argument specializers from the corresponding
generic function.

The method {\bf remove-method} returns the method object if it succeeds and
{\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-method} {generic-function options specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it options\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument
specializers for the arguments of the method that is to be removed.
If the {\it specializers\/} list contains fewer elements than the
lambda list of the corresponding generic function, the remaining
elements are considered to be {\bf t}.

The {\it specializers\/} list can be obtained from a {\bf defmethod}
lambda list by use of the function {\bf lambda-list-specializers}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf lambda-list-specializers

remove-setf-method

defmethod

get-method}

\endcom



\begincom{remove-setf-method}

\label Purpose:

The function {\bf remove-setf-method} removes the {\bf setf} method for
the given name, options, and argument specializers from the corresponding
generic function.

The method {\bf remove-setf-method}  {\bf t} if it succeeds and
{\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-setf-method} {generic-function options specializers setf-specialiers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it options\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of
the argument specializers for the arguments of the
method that is to be removed.  If the {\it specializers\/}
list contains fewer elements than the lambda list of the corresponding
generic function, the remaining elements are considered to be {\bf t}.

The {\it specializers\/} list can be obtained from a
{\bf defmethod} lambda list by use of the function 
{\bf lambda-list-specializers}.

\label Values:

\label See Also:

{\bf lambda-list-specializers

remove-method

defmethod}

\endcom


\begincom{slot-value}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot unless the slot is read-only.

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for using slots
as variables.  Within such a context the slot can be specified by its
slot name, as if it were a lexically bound variable.  The macro 
{\bf with-slots} translates an appearance of the slot name as a variable
into a call to the accessor defined by {\bf defclass}.

\label Syntax:  

\Defmac {with-slots} {\paren {\star{\curly{var $\vert$ varspec}}} \star{\form}}

{\it varspec\/}::$=$ {\paren {var {\star{\curly{options}}}}}

{\it options\/}::$=$  {\tt\vtop{\hbox{:use-accessor {\it flag\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The {\it prefix\/} argument is a string that is prefixed to the slot
name.  No prefix is used if {\it prefix\/} is not specified or is 
{\bf nil} or the null string.

The {\bf :use-accessor} argument in the alternative syntax defaults
to {\bf t}.

\label Values:


\label Remarks:

The {\bf setq} special form may be used with a variable specified
with {\bf with-slots}.

It is an error if the class of {\it var} cannot be inferred from the
lexical context in which it occurs.

\label Examples:

\screen!

[To be written.]
\endscreen!
\endcom
\endChapter
\bye